User's Choice Windows CD/User's Choice Windows CD (CMS Software)(1993).iso/win_u_z/wt_jan92.zip/SHAW.ZIP/COLUMN.TXT

Text File | 1991-12-23 | 29KB | 630 lines

THE VIRTUAL COLUMN
BY RICHARD HALE SHAW

GETTING A HANDLE ON DDE

Windows 3.1 includes DDEML.DLL, a set of routines for creating
and managing DDE conversations. This column explores the library
and presents C++ objects that make DDE simpler and easier than
ever.

This column explores the use of C++ as a Windows development
language. It does so in two ways: first, C++ as *the*
development language for Windows, largely usurping the role of
C; and second, C++ as an object-oriented solution to a
non-object-oriented environment. Let me explain.

First, I believe that C will no longer be the dominant
programming language for Windows developers. I think a number of
developers will find that they can solve their Windows
programming problems with Visual Basic, Turbo Pascal for Windows
or environments like Actor, ToolBook or SmallTalk. But I think
that most Windows programmers who currently use C will move to
C++ over the next 18 months.

Second, Windows -- by any classical definition of OOP -- is
*not* an OOP environment. Sure: you can use a window to tie  data
and code (a window procedure) together, and there's simple
(primitive?) sub-classing. But data encapsulation is relatively
poor compared to other OOP solutions like C++. Plus, when it
comes to inheritance and polymorphism, forget it: Windows
doesn't even come close to offering capabilities like these.
C++, however, offers these OOP features along with the power of
C, and, I believe, is the best tool for creating new Windows
programs.

Consequently, this column will explore Windows programming from
a C++ perspective, and we'll use C++ to create unique solutions
to Windows programming problems. As we proceed, don't hesitate
to send me your thoughts on these issues or on specific ideas
that the column addresses; I'll be sure to share them with
everyone as space permits.

With this in mind, let's look at the first column: on Windows
DDE.

If you've ever written a program that uses Windows' Dynamic  Data
Exchange (DDE), or even attempted to, you know how trying  and
frustrating it is. DDE -- or as my friend and colleague  Charles
Petzold calls it, "the protocol from Hell" -- is one of  the more
exasperating facilities in Windows. The description of  DDE in
the Windows SDK leaves more to the imagination than to  fact, and
the only way to be sure your DDE program worked
properly has been to test it against Microsoft products that
implemented it (after all, we all figure that those guys will
get it right). Unfortunately, this isn't always the case,
either. But many of us have tried, if desparately, to
implement DDE correctly, because the benefit to an
application are so worthwhile.

Fortunately, there's hope. Windows 3.1 now includes DDEML.DLL: a
DLL that packages a number of routines for creating and managing
DDE conversations. This DDL makes DDE infinitely simpler to
implement in your programs, and reduces the possibility of  do so
incorrectly. Plus, you can even use DDEML.DLL under
Windows 3.0.

This article provides an overview of the Windows 3.1 DDEML.DLL
and shows you how to use it in your programs. If you've used DDE
"in the raw" before, you'll have some 'unlearning' to do first.
If you've never programmed DDE before you're in for a treat:
with the DDEML, DDE has never been easier. We'll begin with a
brief overview of what DDE is and how it works. Then, I'll
present you with highlights of the DDE Management library, its
features and how it works. Finally, I'll conclude with some C++
objects that utilize the DDEML.

Keep in mind that Windows 3.1 was still in beta as this column
was written, and the only documentation on the DDEML is in an
on-line file. Further, version of Borland C++ that I'm using
works appears to work with Windows 3.1, but it doesn't do so
officially. The consequence of all this is: there's no absolute
guarantee that the code examples will work without modification
once Windows 3.1 officially arrives. Fortunately, you'll be able
to download an updated version of the code from WTJ at that
time.


An Overview of Traditional DDE

As you're probably aware, DDE lets applications share data.  Like
the Clipboard, DDE operations are often initiated by
the user via an application menu and can transfer data on a  one-
time basis. But unlike the Clipboard, DDE often continues
without user interaction, and it can create on-going data
transfers.

In DDE terminology, the application that initiates the transfer
and requests the data is called the 'client' and the application
that provides the data is the 'server'. The client can
initiate a 'conversation' (i.e., establish a relationship) with
a client and request data from it.

DDE clients and servers 'converse' on specific contexts or
'topics' from which smaller data 'items' are exchanged. A topic
is usually the name of a file or a document, a database table, a
worksheet or an application-specific string. An item is a
specific block of text, a database row(s), a cell(s) or another
application-specific string. A conversation is uniquely
identified by combining the server name and the topic name.  Data
items are distinguished by the server, topic and item  names.

A DDE application can simultaneously engage in multiple
conversations with multiple DDE applications, on the same or on
multiple topics. An application can be a client in one
conversation and simultanelusly a server in another. A server
can supply data to more than one client at a time and a
client can request data from multiple servers at the same time.
Thus, 'AppA' can be a client of 'AppB' and 'AppC', and
simultaneously be a server to both 'AppB' and 'AppC'. The
only hitch is that you keep it all straight.

Traditionally speaking, DDE is a protocol: it establishes a set
of rules that determine what is supposed to happen, and when.
Unfortunately, some of these rules aren't terribly well
defined in the WinSDK (in fact, the DDEML docs are *not*
monuments to great clarity!), and consequently, it's been
difficult to figure out what a DDE application is supposed  to do
in many circumstances. But the essence of a DDE
implementation is that a number of Windows messages are
provided, and these could be used to implement the protocol.

Since Windows doesn't offer any interprocess communication
features in the mature sense (i.e., shared memory, queues,
pipes, etc. as will be found in Windows NT), DDE applications
use messages (prefixed with 'WM_DDE_') to notify other
applications of their intentions, and then transfer data via the
global atom table. This table is a collection of strings that
any Windows application can register with the system, and which
any Windows application can access. Thus to transfer data, a
server application puts the data into the atom table, obtains a
handle to the data, includes the handle as a parameter with the
appropriate DDE message, and sends the latter to the client. The
receiving application processes the message and uses the
included handle to retrieve the data from the atom table.

Finally, since every DDE conversation takes place between two
windows (identified in the conversation by their window handles)
most Windows developers dedicate an invisible window to every
DDE conversation. This is particularly helpful if an application
engages in more than one conversation at a time. This requires
creating the new window and writing a window procedure that  can
respond to the appropriate DDE messages. (Interestingly,  many
Windows developers call these 'object windows' and did so  long
before the Borland application framework of the same name
appeared.)


The DDE Managment Library

Under the hood, the DDEML still uses the approach outlined
above: it communicates with DDE client and server applications
via the standard WM_DDE messages found in Windows. And, it
transfers data between those applications by using the global
atom table. For these reasons, an application that uses DDEML
will be completely compatible with DDE applications written
without the benefit of DDEML.

However, DDEML applications needn't process WM_DDE_* messages or
access the atom table. Instead, the DDEML provides a set of API
functions, along with a few structures and special messages
known as 'transactions'. These facilities serve to hide the
details of traditional DDE conversations. So, your application
need only make a few function calls, and be designed to handle
the transaction messages when they are received.

While DDEML transactions are messages, they're not sent to your
application's window procedure. Instead, you must supply a
special function of your own that, like a window procedure, is
called by DDEML whenever your application receives a
transaction. This 'callback function' (or simply 'callback' for
short) must be capable of processing any transactions that your
application receives from DDEML. In addition, it must be
able to respond by posting transactions as replies and (if your
application is a DDE server) by supplying the appropriate data.

One of the nicer features of the DDEML is that you can filter
out unwanted and unneeded transactions, thus limiting the number
and types of transactions that have to be handled by your
application. These 'transaction filters' are completely dynamic:
you can change them on-the-fly -- even in the midst of a DDE
conversation. The consequence of this feature is that you can
optimize the performance of your DDE application: your callback
will never even receive the filtered messages, and the
sending application will receive a reply transaction indicating
that the transaction it sent wasn't processed (unless the
sending application itself filters out *these* transactions).

The DDEML lets you create DDE conversations that utilize both
synchronous *and* asynchronous transactions. And, the DDEML
supports all the traditional DDE conversational forms: Request,
Advise with notification (a.k.a., 'Warm Link'), Advise with Data
(a.k.a. 'Hot Link'), Execute and Poke. (In talks I've given at
SoftWare Development, I've had more than one student point out
the implicit sexual metaphor in the choice of these terms -- but
they're all legitimate, i.e., chosen by Microsoft.) In addition,
you can use the DDEML to create DDE Monitor, i.e., an
application that can monitor all the DDE conversations taking
place in the system. An example of just such a program is
DDESPY.EXE, which comes with the Windows 3.1 SDK.


Initializing DDEML

The DDEML functions fall into several categories. For instance,
there are functions for initializing the connection between  your
application and the DDEML, and for establishing (or
terminating) DDE conversations. There are transaction management
functions for initiating a transaction and abandoning
asynchronous ones. Other API functions let you create global
data objects, copy data to them and free them. The entire DDEML
API is summarized in the table in Figure 1.  You must #include
DDEML.H in the source files that reference them and link in
DDEML.LIB (DDEML.LIB is the import library for DDEML.DLL --
which should be on the PATH when you run the application).

Before it can call any other DDEML function, you must register
your application with the DDEML by calling DdeInitialize:

DWORD idInst = 0L;
FARPROC lpDdeProc;
WORD errval;
.
.
..
lpDdeProc = MakeProcInstance((FARPROC) DDECallback, hInst);

if(DdeInitialize((LPDWORD) &idInst,(PFNCALLBACK)lpDdeProc,
     APPCMD_CLIENTONLY, 0L))
     return FALSE;

DdeInitialize takes a pointer to a DWORD as its first parameter,
and sets this to an 'application-instance identifier'
-- essentially a handle that refers to that instance of the
task's usage of the DDEML (a task can have more than one
instance of DDEML). Without this handle, the DDEML wouldn't be
able to distinguish one usage of DDEML.DLL from another
by the same task, a problem if the application needs to use the
DDEML more than once at the same time. For instance, suppose an
application is using OLE (which uses DDE to link and embed
objects) while it's using the DDEML. The instance identifier
lets the DDEML keep the application's use of DDE in the OLE DLL
distinct from the application's own use of the DDEML.
Consequently, you have to retain the instance handle when
DdeInitialize returns, and pass it to a great number of the
DDEML API functions.

It's via DdeInitialize that you provide the address of your
application's callback (in the 2nd parameter). If your
application needs to establish DDE conversations with different
behaviors, you can call DdeInitialize for each type of
conversation, passing it a different callback function address,
and receiving a different instance handle each time. Each
instance handle is tied to the callback function passed with
each call to DdeInitialize.

You can also use DdeInitialize to set transaction filters (and
prevent the receipt of a variety of unwanted messages), as well
as specify whether the application is a DDE monitor and or needs
other services from the DDEML.


Server Naming Services

Once an application has registered itself with DDEML, it can
either initiate a conversation (if it's a DDE client) or
register its name and the topics it supports (if it's a DDE
server).

In traditional DDE, the name of a DDE server is based on the
application name. For example, the server name of EXCEL.EXE is
'Excel'. To access Excel as a server with traditional DDE, you
have to specify that name (or rather an atom handle for it) in
the WM_DDE_INITIATE sent by your client application. (Of course,
a client application can always use wildcards invoke
reponses from *all* the available servers.) Plus, there's no way
to know if Excel is available without first attempting to
converse with it.

With DDEML, a server can take on more than one name: the
DdeNameService function lets a DDE server register multiple
names with the system. This function will send an XTYPE_REGISTER
transaction to every DDEML application in the system (except
those that are filtering out this transaction), thus notifying
them that the new server is available. One advantage is that
client applications won't have to attempt to converse with a
server to find out if it's available: they'll be notified once
it's available.

Another advantage is that the server can be more efficient:
DdeNameService can toggle the server's filtering of
XTYPE_CONNECT transactions (which are sent to every server when
a client is trying to start a conversation -- regardless of the
server name specified by the client). Thus, after calling
DdeNameService, the server will only receive XTYPE_CONNECT
transactions when a client specifies one of the registered
server names. A server can also use DdeNameService to
*de-register* a server name: since this causes DDEML to send the
XTYP_UNREGISTER transaction to every DDEML client, client
applications will know when a server is no longer available.

A server can also use DdeNameService to facilitate aliasing: the
server can use different names to indicate different types of
data as it becomes available.


Creating A Conversation

A client application can establish a DDE conversation by calling
DdeConnect:

DWORD idInst;
HSZ hszServer;
HSZ hszTopic;
HCONV hConv;
.
.
.
hConv = DdeConnect(idInst,hszServer, hszTopic,(LPVOID)NULL);

This function sends an XTYP_CONNECT transaction to the specified
server and takes four parameters: the instance handle returned
from DdeInitialize, and two string handles (one for the server
name and the other for the topic name). Either or both of the
string handles can be NULL: as with traditional DDE, a NULL
server name handle will allow a connection with any available
server, and a NULL topic handle will allow a conversation on any
topic supported by the selected server.

The final parameter is a pointer to a CONVCONTEXT structure
(defined in DDEML.H). You can pass a NULL instead, and the
server will receive a default CONVCONTEXT structure along with
the XTYP_CONNECT transaction.  The string handles are created by
calling DdeCreateStringHandle.

In traditional DDE, you have to create an invisible window
that's dedicated to managing the DDE conversation for you. If
DdeConnect finds a server with the specified name that supports
the specified topic, it will return a conversation handle:  in
this implementation of DDEML, a handle to an invisible
window which DDEML creates for you. All messages (even WM_DDE_*
messages) sent to this window are handled by DDEML (it supplies
the window's window procedure) and then passed on to your
application's callback as DDEML transactions. Since there's no
guarantee that this approach will be used in future
implementations of DDEML, you can't rely on the conversation
handle to be a window handle. But you can still use the
conversation handle returned by DdeConnect to refer to a
particular conversation in other calls to the DDEML. And it's
vital for distinguishing between conversations if your
application is maintaining more than one DDEML conversation at a
time.

Note that the DDEML also provides DdeConnectList, which lets a
client application establish more than one conversation at a
time. And, an application can terminate either single or
multiple conversations with DdeDisconnect or DdeDisconnectList,
respectively.

Once an conversation has been established between a client and  a
server, the client application can call DdeClientTransaction  to
receive data from the server:

HCONV hConv;
HSZ hszItem;
HDDEDATA hData;
DWORD dwResult;
.
.
.
hData = DdeClientTransaction((LPBYTE)NULL,0,hConv,hszItem,
     CF_TEXT,XTYP_ADVSTART,1000L,&dwResult);

This function lets a client application receive data on a
one-time basis (cold-link), receive notification of updates
(warm-link) or receive the updated data directly (hot-link). The
first two parameters are supplied in the event that the client
wants to pass data to the server (for the XTYP_EXECUTE or
XTYPE_POKE transactions), and specify a pointer to the data and
the data length. The third parameter is the conversation handle,
and the following one is a string handle that specifies the data
item being requested (like other string handles, created via
DdeCreateStringHandle). The fifth parameter specifies the
Clipboard data format being used (such as CF_TEXT).

The next parameter to DdeClientTransaction is the transaction
type, which can be: XTYP_ADVSTART (to initiate a warm or hot
link), XTYP_ADVSTOP (to terminate such a link), XTYP_EXECUTE (to
issue commands to the server), XTYP_POKE (to offer data to the
server) and XTYP_REQUEST (to make a one-time request for data).
The remaining two parameters specify a timeout value (the
maximum time in milliseconds that a client will wait for a
response from the server) and a result-flag variable. The bits
of the latter are set to designate the result of the
transaction.
If it's successful, DdeClientTransaction returns a handle to a
global memory object that contains the data sent from the
server (provided the transaction was one that requested data).
Your application can pass this HDDEDATA handle to DdeGetData to
retrieve the data:

HDDEDATA hData;
char szBuf[100];
.
.
.
DdeGetData(hData, (LPBYTE)szBuf, 100L, 0L);

In this example, DdeGetData will retrieve the data from a global
memory object (represented by hData) and place it in szBuf. The
last two parameters specify the number of bytes to copy from the
global object to the buffer and at what offset to begin copying.
If you don't know how big the data item is, you can pass a NULL
in place of the local buffer (in this case, szBuf), and
DdeGetData will return the size on bytes of the data item.

If this all sounds terribly complicated, it's not. The listings
accompanying this article show how to use these DDEML functions
in the context of a C++ object that makes a one-time data
request from a DDE server.


CallBack Functions

While the examples above didn't necessitate a callback on the
client side, they don't preclude the client from having one and
the server certainly needed one. If you haven't already
guessed, callbacks are a *lot* like window procedures.  Both
consist of a large *switch* statement, process messages, and are
called by Windows, not your application. DDEML callbacks differ
from window procedures only in the number and types of their
arguments and the messages they process. Here, for example, is a
skeleton callback function:

HDDEDATA EXPENTRY DdeProc(WORD usType,WORD usFmt,HCONV hConv,
          HSZ hsz1,HSZ hsz2,HDDEDATA hData,DWORD lData1,DWORD
lData2)             {
     .
     .
     .
     switch(usType)
     {
          .
          .
          .
          }
     }

As you can see, there are eight arguments passed to a callback
by the DDEML. (It's too bad that Microsoft didn't just supply a
pointer to a structure and pass the structure address to the
callback -- it would have been simpler, easier and faster). The
transaction message is the first parameter, followed by the data
format and the conversation handle. Whether the remaining
parameters (two string handles, a data handle and two
transaction-specific double-words) are used depends on the
transaction that's passed.


Synchronous vs. Asynchronous Transactions

At this point, you should have a general idea of how DDEML
works. Before I present some C++ code examples for using it in
an application, there's on other feature of DDEML that's well
worth mentioning.

DDEML supports both asychronous and synchronous transactions.
The client can conform to the model of traditional DDE and issue
synchronous transactions where the client waits for the
transaction to be processed (as shown in the example using
DdeClientTransaction shown above). Or, it can issue an
asynchronous transactions: the client returns immediately
after calling DdeClientTransaction and proceeds normally; when
the server replies, the client's callback will receive the
response transaction.

Synchronous transactions are simpler, faster and easier
to use. But they can hold up the client if the server takes a
long time to process a transaction or is processing a high
volume of transactions for this and other clients. Asynchronous
transactions, while more complex and difficult to maintain,
allow the client more control while a transaction is in
progress; indeed, a client and go on to issue other transactions
to the same or other servers.


Using C++ with DDEML

To give you a 'taste' of what DDEML will be like (indeed, it
should be available and fully documented not long after this
article appears), I've written a few C++ classes that use it.
(Keep in mind that these won't be fully tested until after DDEML
is released, and that these classes should be considered 'works
in progress'. But they should give you a better idea of how
DDEML can be used from a C++ application.)

The two classes, DDE and DDEClient, can be found in DDE.H
and DDE.CPP. Class DDE contains all the basic facilities that
are needed by a DDE conversation, including the instance handle
and a pointer to the callback function (which an application
that uses the class has to provide). DDEClient relies on the DDE
class for these, and also provides member function to connect to
a DDE server and make a request for data. While I didn't have
time to implemenent member functions that can set up advise
loops (hot and warm links), it'd be simple enough to add them
using the facilities already built into DDEClient.

Both classes compile under Borland C++ 2.0 -- the latest
Borland compiler available at the time this column was
written. (Borland C++ 3.0 was still in Beta, and Microsoft C  7.0
had not reached beta.) Also, both DDEClient and
the DDE class rely on some application classes that I wrote and
have been using over the past year. However, you can
easily reconfigure both of these classes to work with an
application class like Borland's ObjectWindows.

To demonstrate these DDE classes, I wrote a program,
DDECLNT.EXE, which uses DDEML to connect to any DDE
server and retrieve data from it. For example, to connect to
Excel and retrieve rows 1-3, columns 1-4 from ANNUAL.XLS (a
worksheet that comes with Excel):

o    Load Excel
o    Use File|Load to load ANNUAL.XLS
o    Load DDECLNT
o    In DDECLNT's window (a single modal dialog),
     enter "Excel" in the 'Server Name' field, "ANNUAL.XLS" in
     the 'Topic Name' field, and "r1c1:r3c4" in the 'Item Name'
     field.
o    Press the 'Request' button.

This will cause DDECLNT to create a DDEClient object,

DDEClient newClient(Bufs[0].buffer, Bufs[1].buffer,
   (FARPROC)DDEClientCallBack);

and pass it the server name and topic name as the first two
parameters, with the address of a callback function as the last
parameter.

To make a data request, DDECLNT.EXE only needs to call the
Request member function:

newClient.Request(Bufs[2].buffer);

Then, if a call to newClient.GetResult returns TRUE, the program
retrieves the data from newClient with a call to its GetData
member function,

SetDlgItemText(hDlg,RESULT_DATA,(LPSTR)newClient.GetData());

and puts the data directly into one of the data fields in the
main program's dialog.

The DDE and DDEClient classes do all the work.

I've tested the program under Win3.0 and Win3.1. I can't
guarantee it until Win3.1 and the final version of DDEML.DLL  are
available, but you shouldn't have any problems with it. By  the
way: considering how much DDECLNT.EXE does, I'm surprised  that
it's only a little over 10k (of course, the 36k
DDEML.DLL has to be available, too).


Conclusion

As you can see, the DDEML is a powerful addition to Windows 3.1,
but there's a lot to it. C++ certainly makes DDEML easier to
deal with. I'd like to re-visit DDE again in future columns,
once Win3.1 arrives and these classes have time to mature. But,
until next month, enjoy!

===========================================
[figure 1]

Session Management
------------------------
DdeInitialize           Registers an application with the DDEML
DdeUninitialize         Frees an application's DDEML resources

Conversation Management
------------------------
DdeConnect              Establishes a conversation with a server
DdeConnectList          Establishes multiple DDE conversations
DdeDisconnect           Terminates a DDE conversation
DdeDisconnectList       Destroys a DDE conversation list
DdeEnableCallback       Enables or disables one or more DDE conversations
DdePostAdvise           Prompts a server to send advise data to a client
DdeQueryConvInfo        Retrieves information about a DDE conversation
DdeQueryNextServer      Obtains the next handle in a conversation list

Transaction Management
------------------------
DdeAbandonTransaction   Abandons an asynchronous transaction
DdeClientTransaction    Begins a DDE data transaction

Data Management
------------------------
DdeAccessData           Accesses a DDE global memory object
DdeAddData              Adds data to a DDE global memory object
DdeCreateDataHandle     Creates a DDE data handle
DdeFreeDataHandle       Frees a global memory object
DdeGetData              Copies data from a global memory object to a buffer
DdeUnaccessData         Frees a DDE global memory object

String Management
------------------------
DdeCmpStringHandles     Compares two DDE string handles
DdeCreateStringHandle   Creates a DDE string handle
DdeFreeStringHandle     Frees a DDE string handle
DdeKeepStringHandle     Increments the use count for a string
handle DdeQueryString   Copies string-handle text to a buffer

Miscellaneous Functions
------------------------
DdeGetLastError         Returns the error code set by a DDEML function
DdeNameService          Registers or unregisters server name(s)
DdeSetUserHandle        Associates a user-defined handle with a transaction

=================================================================